DISCUSSION

If you create a text object, it is your responsibility to dispose of it after use.

SEE ALSO

The JMDisposeTextRef.

The JMGetTextBytes function.

JMDisposeTextRef

Removes a text object.

OSStatus JMDisposeTextRef(JMTextRef textRef);

textRef

The text object you want to remove.

function result

A result code; see JManager Result Codes.

DISCUSSION

If you create a text object, it is your responsibility to dispose of it after use.

SEE ALSO

The JMNewTextRef function.

JMCopyTextRef

Duplicates a text object.

OSStatus JMCopyTextRef (

const JMTextRef textRefSrc, JMTextRef* textRefDst);

textRefSrc

The text object you want to duplicate.

textRefDst

A pointer to a text object. On return, this parameter contains a copy of the textRefSrc text object.

function result

A result code; see JManager Result Codes.

JMGetTextLength

Returns the length of the string in a text object.

OSStatus JMGetTextLength (

const JMTextRef textRef, UInt32* textLengthInCharacters);

textRef

The text object containing the string.

textLengthInCharacters

A pointer to an integer. On return, this parameter contains the length of the string, in characters.

function result

A result code; see JManager Result Codes.

DISCUSSION

This function returns the string length in characters rather than bytes, since the Unicode standard uses 2 bytes per character, while standard Mac OS encodings and UTF-8 use only 1.

JMGetTextBytes

Retrieves characters in a text object in the appropriate text encoding.

OSStatus JMGetTextBytes (

const JMTextRef textRef, JMTextEncoding dstEncoding, void* textBuffer, UInt32 textBufferLength, UInt32* numCharsCopied);

textRef

The text object containing the string to retrieve.

dstEncoding

The text encoding you want to use for the string.

textBuffer

A pointer to a buffer. on return, this parameter is the retrieved string.

textBufferLength

The length of the buffer, in bytes.

numCharsCopied

A pointer to an integer. On return, this parameter is the actual length of the string retrieved, in characters.

function result

A result code; see JManager Result Codes.

DISCUSSION

The number of characters retrieved is dependent on the size you specify for the buffer as well as on the text encoding. For example, Unicode characters can take 2 bytes per character.

SEE ALSO

The JMNewTextRef function.

JMTextToJNIJavaString

Returns the text object as a JNI-style Java string.

jstring JMTextToJNIJavaString (
                     JMTextRef textRef,
                     JMSessionRef session,
                     JNIEnv * env);

textRef

The text object to convert.

session

The session that contains the text object.

env

The JNI environment to associated with the Java string.

function result

A reference to a Java string.

DESCRIPTION

This reference is the only reference to the string; if you do not use it, the session will garbage-collect it.

SEE ALSO

The JMTextToMacOSCStringHandle function.

JMTextToJavaString

Returns the text object as a JRI-style Java string.

jref JMTextToJavaString (const JMTextRef textRef);

textRef

The text object to convert.

function result

A reference to a Java string

DISCUSSION

This reference is the only reference to the string; if you do not use it, the session will garbage-collect it.

Unless you specifically need to use the Java Runtime Interface (JRI), you should use the JMTextToJNIJavaString function instead.

SEE ALSO

The JMTextToMacOSCStringHandle function.

JMTextToMacOSCStringHandle

Returns the text object as a null-terminated Mac OS C string in the current system text encoding.

Handle JMTextToMacOSCStringHandle(const JMTextRef textRef);

textRef

The text object to convert.

function result

A handle to a Mac OS C string.

DISCUSSION

You must dispose of the handle (by calling the Mac OS Toolbox function DisposeHandle ) after you are finished using it.

IMPORTANT

Since the text conversion is from Unicode to a Mac OS string, some data may be lost if appropriate character mappings do not exist (that is, some Unicode characters may not be represented in the Mac OS encoding). You should be aware that the JMTextToMacOSStringHandle function cannot indicate whether data loss occurred.